package com.chengqs.summer.io;

import java.io.IOException;
import java.io.InputStream;

/**
 * {@code InputStreamCallback} 是一个函数式接口，用于定义处理 {@link InputStream} 的回调逻辑。
 *
 * <p>通过使用此接口，您可以轻松地将输入流的处理逻辑封装到一个可重用的回调中，
 * 这对于需要灵活处理流数据的场景非常有用。此接口特别适用于文件、网络连接、
 * 数据库等输入流处理场景。
 *
 * <p>该接口的设计遵循以下设计模式：
 *
 * <ul>
 *   <li><strong>策略模式 (Strategy Pattern):</strong>
 *   <p>通过定义单一抽象方法 {@code doWithInputStream}，可以用不同的实现来定义如何处理输入流，
 *   从而实现不同的策略。这种模式允许使用者在不修改类结构的情况下定制处理行为。
 *
 *   <li><strong>函数式接口 (Functional Interface):</strong>
 *   <p>通过使用 {@link FunctionalInterface} 注解，该接口仅定义一个抽象方法，
 *   支持使用 lambda 表达式或方法引用来实现接口，简化了接口的实现过程。
 * </ul>
 *
 * <h2>使用场景</h2>
 * <p>以下是一些常见的使用场景：
 * <ul>
 *   <li>读取文件内容并进行处理，例如统计字数或过滤内容。</li>
 *   <li>从网络流中读取数据，并将其解析为对象或数据结构。</li>
 *   <li>处理从数据库或其他输入源读取的二进制数据。</li>
 * </ul>
 *
 * <h2>示例代码</h2>
 * <pre>{@code
 * public class InputStreamExample {
 *
 *     public static void main(String[] args) {
 *         try {
 *             // 示例使用FileInputStream读取文件
 *             FileInputStream fis = new FileInputStream("example.txt");
 *
 *             // 使用lambda表达式实现InputStreamCallback接口
 *             InputStreamCallback<String> callback = (InputStream inputStream) -> {
 *                 StringBuilder sb = new StringBuilder();
 *                 int ch;
 *                 // 从输入流中读取数据并转换为字符串
 *                 while ((ch = inputStream.read()) != -1) {
 *                     sb.append((char) ch);
 *                 }
 *                 return sb.toString();
 *             };
 *
 *             // 使用executeWithInputStream方法执行流处理回调
 *             String result = executeWithInputStream(fis, callback);
 *
 *             System.out.println("读取到的文件内容：");
 *             System.out.println(result);
 *         } catch (IOException e) {
 *             e.printStackTrace();
 *         }
 *     }
 *
 *     // 定义一个方法来处理InputStream和回调
 *     public static <T> T executeWithInputStream(InputStream stream, InputStreamCallback<T> callback) throws IOException {
 *         try {
 *             // 执行传入的回调方法
 *             return callback.doWithInputStream(stream);
 *         } finally {
 *             // 确保输入流被正确关闭
 *             stream.close();
 *         }
 *     }
 * }
 * }</pre>
 *
 * @param <T> 该接口的实现返回的结果类型，可以是从输入流中获取并处理后的任意类型。
 * @throws IOException 处理输入流过程中可能发生的 I/O 异常。
 */
@FunctionalInterface
public interface InputStreamCallback<T> {

    /**
     * 使用 {@link InputStream} 执行特定的操作。
     *
     * <p>实现此方法时，您可以通过输入流读取数据并返回所需的结果。
     * 该方法可能会在读取或处理流时抛出 {@link IOException}。
     *
     * @param stream 需要处理的输入流。
     * @return 从输入流中读取和处理后的结果，类型由实现类定义。
     * @throws IOException 如果在读取或处理输入流时发生 I/O 错误。
     */
    T doWithInputStream(InputStream stream) throws IOException;
}

